fix(webview-message-handler): enforce workspace containment for markdown-sourced openFile requests - #1762

Part 1 of the 2-way split of #1257 (supersedes its extension-side half; webview-side unit: #1763). Content source of record: 99025b1fb..6c1eee6d3 (the head of #1257).

Context

#1257 was red on platform-unit-test → verify:coverage-contract: that check compared the extension coverage population against a hardcoded baseline (469 files / 30,229 lines) and #1257's head predated #1644, which replaced the hardcoded baseline with the shared coverage-contract.mjs merge. This branch is based on current main (f78064753), which already contains #1644, so no baseline edit is needed here.

What this unit does

Extension-side defense for #1256: when a webview openFile request is tagged fromMarkdown: true (i.e. it came from a markdown link), the path is validated against the workspace before it can be opened, and any path that escapes the workspace is rejected with a localized error (new i18n key path_outside_workspace across all 18 locales). Untagged requests keep the legacy behavior — the existing ClineProvider.spec.ts suite (unchanged here) already covers that path.

Containment has two lines, both applied to tagged requests at the handler boundary:

1. Lexical — the path is resolved against the workspace and checked with the production isPathOutsideWorkspace (src/utils/pathUtils.ts).
2. Realpath — isRealPathOutsideWorkspace (new, src/utils/pathUtils.ts) resolves the filesystem's real targets before the check, so a symlink inside a workspace folder cannot point at a file outside it. Paths that do not exist yet (the create: true flow) are checked via their deepest existing ancestor. A dangling symlink (an entry that exists but whose target cannot be resolved — realpath ENOENT without the path being absent) fails closed, because a creation flow would follow it and could escape the workspace; a genuinely absent entry keeps walking. Fails closed on unresolvable targets and on unexpected lstat errors.

In addition, tagged paths are percent-decoded to a fixed point (decodeUntrustedPathToStable, new) at the containment boundary: openFile (src/integrations/misc/open-file.ts) decodes the path AFTER these checks, so a request like ./%2e%2e/%2e%2e/.env would otherwise pass containment as a literal and escape only after that later decode. Double-encoded payloads (%252e%252e) are caught the same way; filenames with a bare % that is not a valid escape (e.g. report 50%.md) are left unchanged (the lenient semantics openFile already applies).

• src/core/webview/webviewMessageHandler.ts: containment guard for tagged requests (3-way merged against current main, clean, zero conflicts — main's refactor(code-index): extract manager registry #1622 code-index refactor touched this file since fix(webview): render expanded task header text as markdown with consistent scrollbar #1257's merge base)
• src/utils/pathUtils.ts: new decodeUntrustedPathToStable + isRealPathOutsideWorkspace
• src/core/webview/__tests__/webviewMessageHandler.openFile.spec.ts: focused suite (33 tests) — runs the production isPathOutsideWorkspace against a mutable mock workspace (multi-root, no-folders) plus a deterministic fs.promises.realpath + fs.promises.lstat model (no real filesystem); covers relative/absolute open+reject, encoded and double-encoded traversal, legitimately encoded filenames, symlink escape (including a symlinked workspace root), dangling-symlink fail-closed (handler and helper), lstat-error fail-closed, the creation flow, multi-root, and legacy untagged behavior
• src/i18n/locales/*/common.json: path_outside_workspace key × 18 locales (+1 each)

Part of #1256. Merge before the webview-side unit (#1763) so the containment check is in place before the webview starts sending tagged requests.

Automated review findings (addressed in commits e98713a, ceff8bf, 7f3668d, e182070)

• Security Boundaries (error) — URI-encoded traversal bypass: fixed by the percent-decode-to-fixed-point at the containment boundary; regression tests for %2e%2e and %252e%252e payloads.
• Security Boundaries (error, pre-merge checklist) — dangling symlink in realPathOfExistingAncestor: an entry that exists but whose target is unresolvable failed realpath with ENOENT and was treated as a nonexistent path, so the walk fell back to the (in-workspace) ancestor while a creation flow (mkdir -p) would follow the link and escape the workspace. Fixed (7f3668d): on ENOENT the entry is lstated first (lstat does not follow the final entry) — a dangling symlink fails closed, a genuinely absent entry keeps walking, and any other lstat error also fails closed. Regression tests: dangling symlink rejected at the handler and in the helper, plus the lstat EACCES fail-closed path.
• Symlink bypass (file comment): fixed by the realpath-based containment (line 1543 comment).
• Regression Evidence (warning, pre-merge checklist) — the symlink check was only exercised with symlinks inside the workspace: added the requested test where the workspace root itself is a symlink — the realpath containment resolves to the real root and the open succeeds (d4d63d4).
• Regression Evidence (warning) — the spec mocked isPathOutsideWorkspace with a hand-written copy; the production predicate now runs unmocked with per-case workspace folders (in-workspace, outside, no-folders, multi-root) per the requested resolution.
• Mutation gate (e182070): one equivalence directive added — the if (stat.isSymbolicLink()) condition is always true at every reachable point (lstat succeeding after a realpath ENOENT can only be a dangling symlink), so Stryker's true/false replacements are unobservable; the false replacement is pinned by the dangling-symlink tests.

Line budget (standalone vs base f780647)

863+/5− = 868 a+d / 22 files — soft overshoot (400), hard cap (1000) not reached. The delta vs the original 251 is the review-gate-mandated hardening: ~200 executable lines (decode + realpath containment + dangling-symlink fail-closed) and ~540 test lines (33-test openFile suite + new locale-bundles completeness suite).

Fidelity (machine-verified)

zdt split verify --contract contract-a.json --worktree <wt> --head e18207031 → PASS, 0 violations: all 18 locale files and the source content of the handler/spec are a subset of source 99025b1fb..6c1eee6d3; the CR-hardening lines are sanctioned by the contract's allowNew (handler: source + 19 sanctioned new lines; openFile spec: source + 279; pathUtils: NEW/allowNew; locale-bundles.spec.ts: NEW/allowNew). webviewMessageHandler.ts byte-differs from source only by the clean 3-way merge against current main plus the sanctioned hardening.

Mutation gate (local preflight)

• extension (e182070): 61 valid / 60 killed / 1 timeout / 0 survived / 0 noCoverage → PASS (caps: ≤500 changed executable lines, ≤400 valid mutants)
• directive hygiene: clean (0 issues); 1 equivalence directive on the dangling-symlink condition (unobservable true/false replacements — lstat succeeding after a realpath ENOENT can only be a dangling symlink; the false replacement is pinned by the dangling-symlink tests)

Changed-line coverage (local, this head)

zdt coverage changed --worktree <wt> --base f78064753 --coverage-dir src/coverage (head e182070) → PASS (binary, by once): 66 covered / 0 uncovered / 0 exempted / 0 unmeasurable, across webviewMessageHandler.ts (25/25 changed lines), pathUtils.ts (120/120) and all 18 locale bundles (imported by the new locale-bundles.spec.ts, which also pins errors.path_outside_workspace in every locale).

Verification (local, this head)

• pnpm --dir src exec vitest run core/webview/__tests__/webviewMessageHandler.openFile.spec.ts core/webview/__tests__/ClineProvider.spec.ts i18n/__tests__/locale-bundles.spec.ts → 210/210 passed (openFile suite 33, locale-bundles 18, legacy ClineProvider suite 159)
• pnpm --dir src exec eslint --prune-suppressions --max-warnings=0 <changed files> → clean, no suppression-count change
• pre-push hook: check-types + full lint 11/11 packages passed